To use GLR, a client application first establishes a GLR session:
GLrSession session; session = glrOpenSession(NULL);When NULL is passed to glrOpenSession, the GLR server hostname is determined by the GLR_SERVER environment variable. Otherwise, the string names the GLR server to connect to; the empty string connects to a GLR server on the local machine. The GLrSession returned is passed to subsequent GLR calls; however, a NULL return value indicates failure. glrCloseSession is passed an open GLrSession to be closed down.
Given a GLR session handle, the client can allocate a GLR canvas type. An attribute list is supplied that describes the minimum set of frame buffer capabilities requested. For example:
GLrCanvasType canvasType;
int atts[] = { GLR_RGBA, GLR_DEPTH_SIZE, 16,
GLR_RED_SIZE, 1, GLR_GREEN_SIZE, 1, GLR_BLUE_SIZE, 1,
GLR_SAMPLE_SGIS, 4 /* multisampling */, 0 };
canvasType = glrGetCanvasType(session, atts);
A GLR canvas type roughly corresponds to an
OpenGL-capable X visual. glrGetCanvasType operates much like
GLX's glXChooseVisual routine. If glrGetCanvasType returns
NULL, a canvas type meeting the attribute list requirements was
not available.
Once a canvas type is gotten, a GLR canvas can be created by calling glrCreateCanvas:
GLrCanvas canvas; canvas = glrCreateCanvas(canvasType, NULL);The second parameter can be used to name an existing GLR canvas with which display lists are shared. Unlike GLX in which a GLX drawable and context are two distinct entities, GLR ties together rendering context state with frame buffer state. The set of frame buffer capabilities supported by a canvas is determined by the canvas's canvas type.
Calling glrEstablishRenderState lets a client make OpenGL calls to establish OpenGL render state for a GLR canvas (without retaining frame buffer state). For example:
int success;
success = glrEstablishRenderState(canvas);
if (!success) {
/* failed */
}
Subsequent OpenGL calls (until another OpenGL context is selected)
affect the canvas's OpenGL state machine. During this period, OpenGL
state can be updated and retrieved (including creating display lists
and use of selection and feedback). Because the canvas's frame buffer
state is retained only within a render interval, any frame buffer state
returned by an OpenGL command (for example, glReadPixels) is
undefined.